<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
  <link rel="stylesheet" media="screen" type="text/css" href="./style.css" />
  <link rel="stylesheet" media="screen" type="text/css" href="./design.css" />
  <link rel="stylesheet" media="print" type="text/css" href="./print.css" />

  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
</head>
<body>
<div class="dokuwiki export">

<p>
<em>Translations of this page are also available in the following languages:</em> <a href="geda-scm.ru.html" class="wikilink1" title="geda-scm.ru.html">Русский</a>.
</p>

<h1 class="sectionedit1"><a name="geda_uses_git" id="geda_uses_git">gEDA uses git</a></h1>
<div class="level1">

<p>
gEDA uses <strong>git</strong> for source code management.  git is a distributed version control system, where every user has his or her own full copy of the revision history.
</p>
<ul>
<li class="level1"><div class="li"> <a href="http://git.or.cz/" class="urlextern" title="http://git.or.cz/"  rel="nofollow">official git website</a></div>
</li>
<li class="level1"><div class="li"> <a href="http://www.kernel.org/pub/software/scm/git/docs/" class="urlextern" title="http://www.kernel.org/pub/software/scm/git/docs/"  rel="nofollow">git documentation online</a></div>
</li>
<li class="level1"><div class="li"> <a href="http://en.wikipedia.org/wiki/Git_(software)" class="interwiki iw_wp" title="http://en.wikipedia.org/wiki/Git_(software)">git Wikipedia page</a></div>
</li>
</ul>

<p>
Some nice tutorials:
</p>
<ul>
<li class="level1"><div class="li"> <a href="http://wiki.sourcemage.org/Git_Guide" class="urlextern" title="http://wiki.sourcemage.org/Git_Guide"  rel="nofollow">Git Guide</a></div>
</li>
<li class="level1"><div class="li"> <a href="https://git.wiki.kernel.org/index.php/GitSvnCrashCourse" class="urlextern" title="https://git.wiki.kernel.org/index.php/GitSvnCrashCourse"  rel="nofollow">git Crash Courses</a></div>
</li>
</ul>

</div>
<!-- EDIT1 SECTION "gEDA uses git" [106-630] -->
<h2 class="sectionedit2"><a name="access_the_repository_anonymously" id="access_the_repository_anonymously">Access the repository anonymously</a></h2>
<div class="level2">

<p>
To clone the geda-gaf.git repository (or any repository hosted at <a href="http://git.geda-project.org/" class="urlextern" title="http://git.geda-project.org"  rel="nofollow">git.geda-project.org</a>) using anonymous git access:
</p>
<pre class="code">git clone git://git.geda-project.org/geda-gaf.git</pre>

<p>
or
</p>
<pre class="code">git clone git://git.geda-project.org/pcb.git</pre>

<p>
For different repositories hosted at git.geda-project.org, just substitute the last part of the above <acronym title="Uniform Resource Locator">URL</acronym>.
</p>

<p>
There is a <a href="http://hjemli.net/git/cgit/about/" class="urlextern" title="http://hjemli.net/git/cgit/about/"  rel="nofollow">cgit</a> interface to the repositories of the various projects. Just point a www browser to <a href="http://git.geda-project.org/" class="urlextern" title="http://git.geda-project.org/"  rel="nofollow">http://git.geda-project.org/</a> .
</p>

</div>
<!-- EDIT2 SECTION "Access the repository anonymously" [631-1211] -->
<h2 class="sectionedit3"><a name="access_the_repository_with_write_permission" id="access_the_repository_with_write_permission">Access the repository with write permission</a></h2>
<div class="level2">

<p>
For developer git access, you should write DJ Delorie or Traumflug an email with your <acronym title="Secure Shell">SSH</acronym> public key and your preferred user name. They&#039;ll install this key on the server, then. Having done so, the git <acronym title="Uniform Resource Locator">URL</acronym> to push to is (note the <em>:65</em>):
</p>
<pre class="code">ssh://git@git.geda-project.org:65/&lt;repository&gt;.git</pre>

<p>
Note: If you&#039;re having trouble pushing commits upstream, make sure you&#039;re using git 1.5 or newer.
</p>

<p>
Accordingly, to grab a repository copy with write privileges you&#039;d do this:
</p>
<pre class="code">git clone ssh://git@git.geda-project.org:65/&lt;repository&gt;.git</pre>

<p>
If you have a read-only clone already you can change it to one with write access:
</p>
<pre class="code">git remote remove origin
git remote add origin ssh://git@git.geda-project.org:65/&lt;repository&gt;.git</pre>

<p>
Having this done, your local clone works just as before, just a <code>git push origin &lt;branch&gt;</code> succeeds.
</p>

</div>

<h4><a name="a_key_unique_for_geda" id="a_key_unique_for_geda">A key unique for gEDA</a></h4>
<div class="level4">

<p>
You can use a separate key for accessing the gEDA git access. This has no further advantage other than having a unique key. In this case you may also need to add a line to your ~/.ssh/config file to specify this alternate key:
</p>
<pre class="code">Host git.geda-project.org
Port 65
IdentityFile ~/.ssh/gedaproject_dsa</pre>

<p>
Note that the file you refer to here is the private key, where the file you send for the server side is the corresponding public key.
</p>

</div>
<!-- EDIT3 SECTION "Access the repository with write permission" [1212-2563] -->
<h2 class="sectionedit4"><a name="commit_changes" id="commit_changes">Commit changes</a></h2>
<div class="level2">

</div>
<!-- EDIT4 SECTION "Commit changes" [2564-2591] -->
<h3 class="sectionedit5"><a name="set_up_user_information" id="set_up_user_information">Set up user information</a></h3>
<div class="level3">

<p>
You should make sure that your username &amp; e-mail address are set in your git configuration file.
</p>
<pre class="code">$ git config --global user.name &quot;Your Name Comes Here&quot;
$ git config --global user.email you@yourdomain.example.com</pre>

</div>
<!-- EDIT5 SECTION "Set up user information" [2592-2844] -->
<h3 class="sectionedit6"><a name="commit_patches_from_other_contributors" id="commit_patches_from_other_contributors">Commit patches from other contributors</a></h3>
<div class="level3">

<p>
If you apply a patch from someone else (e.g. from a launchpad patch record) there are a few things to consider.
Git stores two different names and e-mail addresses for a given commit: the “author” of the patch, and the “committer” of the patch, so these details must be set correctly when making the commit.
</p>

<p>
First of all, check a few things:
</p>
<ul>
<li class="level1"><div class="li"> You have the latest version of the patch.</div>
</li>
<li class="level1"><div class="li"> The author of the patch is happy for it to be committed (and wasn&#039;t still working on it)</div>
</li>
<li class="level1"><div class="li"> That the you&#039;re happy with the patch, and taking responsibility for committing those changes.</div>
</li>
</ul>

<p>
For simplicity, start from an unmodified up-to date tree (git status shows no changes).
</p>

<p>
Apply the patch as usual (as an example):
</p>
<pre class="code">$ patch -p1 &lt; example_changes.patch</pre>

<p>
You can also use the git apply command:
</p>
<pre class="code">$ git apply example_changes.patch</pre>

<p>
If the patch needs any minor editing before it is committed (eg. white-space changes), please inform the author this was done.
They may have other work based on their patch and will want to know if there were changes to the applied version.
</p>

<p>
Note: <em>This is easy to miss accidentally if your editor introduces tabs. Please avoid letting it do so!</em>
</p>

<p>
For every file changed, added or removed, you need to inform git before it will commit the changes. To see the modified files, run:
</p>
<pre class="code">$ git status</pre>

<p>
For speed, the command:
</p>
<pre class="code">$ git add -u</pre>

<p>
will update all files which git tracks, including any files which were deleted.
</p>

<p>
For adding any new files the patch introduced, use the command
</p>
<pre class="code">$ git add new_file.c</pre>

<p>
Note: git add also takes wild-cards.
</p>

<p>
Commit the patch, making sure that the Author&#039;s name and e-mail address are specified:
</p>
<pre class="code">$ git commit --author &quot;Author&#039;s Name Comes Here &lt;author@example.com&gt;&quot;</pre>

<p>
As an alternative, you can set the GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL environment variables before issuing the normal commit command
</p>

</div>
<!-- EDIT6 SECTION "Commit patches from other contributors" [2845-4768] -->
<h3 class="sectionedit7"><a name="write_good_commit_messages" id="write_good_commit_messages">Write good commit messages</a></h3>
<div class="level3">

<p>
The commit message format is as follows: a *strictly* one-line summary of the patch, followed by a blank line, followed by a long description.  If you can fit the whole description of the patch on one line, that&#039;s fine; don&#039;t bother with the long description.
</p>

<p>
The one-line summary is used for generating e-mail subject lines, and for the gitk &amp; gitweb log displays.  Having a good one-line summary is really useful, because it means those tools can be used to quickly find a commit of interest.
</p>

<p>
<strong>Do not</strong> put a list of files changed into commit messages.  This information can be trivially obtained using the git tools.
</p>

<p>
Example:
</p>
<pre class="code">Added new GedaList class derived from GObject

This abstracts a GList with API for write access. Its main use is in list
change notification, as it emits a &quot;changed&quot; g_signal when modified.
Read only access to the underlying GList is provided by an accessor,
currenly implemented as a macro.</pre>

</div>
<!-- EDIT7 SECTION "Write good commit messages" [4769-5748] -->
<h2 class="sectionedit8"><a name="keep_the_local_copy_current" id="keep_the_local_copy_current">Keep the local copy current</a></h2>
<div class="level2">

<p>
For those who are are not merging changes back into the central git repository you can run:
</p>
<pre class="code">$ git pull</pre>

<p>
However, for those of you who are going to be pushing your changes back into the central git repository, using git pull will clutter up the history with merge messages (“Merge branch &#039;master&#039;”).  To avoid this you should run:
</p>
<pre class="code">$ git fetch
$ git rebase origin</pre>

</div>
<!-- EDIT8 SECTION "Keep the local copy current" [5749-6159] -->
<h2 class="sectionedit9"><a name="commit_changes_to_the_local_git_repository" id="commit_changes_to_the_local_git_repository">Commit changes to the local git repository</a></h2>
<div class="level2">
<pre class="code">$ git commit -a</pre>

<p>
This command will find all changed files that git knows about (added with git-add) and prompt you for a commit message.  Be sure to follow the above commit message convention if you plan on pushing your changes to the central repository.
</p>

<p>
If you want to commit files in the current directory or want to explicitly commit only certain files, do not specify the -a flag and/or specify the individual filenames on the command line like:
</p>
<pre class="code">$ git commit filename1 filename2</pre>

</div>
<!-- EDIT9 SECTION "Commit changes to the local git repository" [6160-6705] -->
<h2 class="sectionedit10"><a name="undo_any_uncommitted_local_changes" id="undo_any_uncommitted_local_changes">Undo any uncommitted local changes</a></h2>
<div class="level2">
<pre class="code">$ git checkout -f</pre>

<p>
Note this will discard any changes to any files that are being tracked by git.
</p>

<p>
If you want to just discard edits in a single file, just run:
</p>
<pre class="code">$ git checkout path/to/file/to/discard</pre>

<p>
If you want to discard all edits from the current directory and downward recursively, just run:
</p>
<pre class="code">$ git checkout .</pre>

</div>
<!-- EDIT10 SECTION "Undo any uncommitted local changes" [6706-7076] -->
<h2 class="sectionedit11"><a name="fix_a_less_than_perfect_last_commit" id="fix_a_less_than_perfect_last_commit">Fix a less than perfect last commit</a></h2>
<div class="level2">
<pre class="code">$ Edit whatever files
$ git commit --amend filename1..filenameN</pre>

<p>
This will pickup any changes you made and recommit them again with the previous commit message.
</p>

</div>
<!-- EDIT11 SECTION "Fix a less than perfect last commit" [7077-7291] -->
<h2 class="sectionedit12"><a name="track_a_branch" id="track_a_branch">Track a branch</a></h2>
<div class="level2">
<pre class="code">$ git checkout --track -b &lt;local name&gt; origin/&lt;remote name&gt;</pre>

<p>
This will create a branch with the &lt;local name&gt; which tracks the &lt;remote name&gt;&#039;d branch.
</p>

</div>
<!-- EDIT12 SECTION "Track a branch" [7292-7472] -->
<h2 class="sectionedit13"><a name="create_a_personalized_branch" id="create_a_personalized_branch">Create a personalized branch</a></h2>
<div class="level2">

<p>
If you have write permission to the git repository of the gEDA project, you can create personalized branches for your patches. This is recommend to facilitate tests, review and finally application of the patches to the master branch of the application. For this purpose a personalized name space is available in the git repositories. The prefix of this name space is <code>home/&lt;user_name&gt;/</code>, where <code>&lt;user_name&gt;</code> is your user name. 
</p>

<p>
First create the branch locally and simultaneously switch to it as the current branch:
</p>
<pre class="code"> $ git checkout -b home/&lt;user_name&gt;/&lt;name_of_the_branch&gt;</pre>

<p>
Make some changes. Stage the changes and issue a commit:
</p>
<pre class="code"> $ git stage &lt;files to commit&gt;
 $ git commit -F &lt;commit_message&gt;</pre>

<p>
Where <code>&lt;commit_message&gt;</code> points to a file which contains the commit message. 
</p>

<p>
To publish the changed branch to the remote repository do:
</p>
<pre class="code"> $ git push origin home/&lt;user_name&gt;/&lt;name_of_the_branch&gt;</pre>

<p>
The first push to a branch creates it on the remote server.
For a little more convenience, you can advise git to always push to the current branch:
</p>
<pre class="code"> $ git config --global push.default current</pre>

<p>
Skip the option <code>--global</code> if you want this to be active only in this particular git project. With this directive the command above reduces to a mere 
</p>
<pre class="code"> $ git push
 </pre>

</div>
<!-- EDIT13 SECTION "Create a personalized branch" [7473-8799] -->
<h2 class="sectionedit14"><a name="delete_a_personalized_branch" id="delete_a_personalized_branch">Delete a personalized branch</a></h2>
<div class="level2">

<p>
In case you&#039;d rather not have your branch sitting indefinitely in the remote repository, you can issue a delete directive. To delete the branch on the server do:
</p>
<pre class="code"> $ git push origin --delete home/&lt;user_name&gt;/&lt;name_of_the_branch&gt;</pre>

<p>
To delete the branch on the local repository, too:
</p>
<pre class="code"> $ git branch --delete home/&lt;user_name&gt;/&lt;name_of_the_branch&gt;
 </pre>

</div>
<!-- EDIT14 SECTION "Delete a personalized branch" [8800-9188] -->
<h2 class="sectionedit15"><a name="fetch_a_development_branch_from_other_people" id="fetch_a_development_branch_from_other_people">Fetch a development branch from other people</a></h2>
<div class="level2">

<p>
Beside the <a href="http://git.geda-project.org/" class="urlextern" title="http://git.geda-project.org/"  rel="nofollow">http://git.geda-project.org/</a> repository we have a mirror of that repository at <a href="http://repo.or.cz/w/geda-gaf.git" class="urlextern" title="http://repo.or.cz/w/geda-gaf.git"  rel="nofollow">http://repo.or.cz/w/geda-gaf.git</a>. Some of the developers have forks of that repository with new feature branches.
</p>

<p>
If you like to test one of the feature branches you have to fetch it from their repository.
The easiest way to get a branch is to use the fetch command.
</p>
<pre class="code">  $ git fetch repository_url remote_branchname:local_branchname</pre>

<p>
<strong>Examples:</strong>
Getting the <em>cairo_experiment</em> branch from Peter C. would look like this:
</p>
<pre class="code">  $ git fetch git://repo.or.cz/geda-gaf/pcjc2.git cairo_experiment:peters_cairo_experiment</pre>

<p>
Now you can switch to the local copy of the branch <em>peters_cairo_experiment</em> and play with it.
</p>

<p>
It is also possible to add multiple remote forks into the local repository:
</p>
<pre class="code">  $ git remote add &lt;name&gt; &lt;url&gt;
  $ git fetch &lt;name&gt;</pre>

<p>
As long as &lt;name&gt; is unique you will be able to follow their work without the
need to create local branches. With a tool like gitk it is now possible to keep
an eye on development in various feature branches on various forks:
</p>
<pre class="code">  $ gitk --all</pre>

<p>
<strong>Examples:</strong>
</p>
<pre class="code">  $ git remote add peter-b https://github.com/peter-b/geda-gaf.git
  $ git fetch peter-b
  $ git remote add gareth8118 https://github.com/gareth8118/geda-gaf.git
  $ git fetch gareth8118
  $ git remote add bert https://github.com/bert/geda-gaf.git
  $ git fetch bert
  $ gitk --all</pre>

<p>
Now gitk can become quite filled up, but <strong>File</strong>→<strong>List references</strong> (<kbd>F2</kbd>) will open
a dialog for easier navigation.
</p>

<p>
Updating favourite remotes will then boil down to:
</p>
<pre class="code">  $ git fetch --all
  </pre>

</div>
<!-- EDIT15 SECTION "Fetch a development branch from other people" [9189-10858] -->
<h2 class="sectionedit16"><a name="format_a_patch_to_send_to_the_developers" id="format_a_patch_to_send_to_the_developers">format a patch to send to the developers?</a></h2>
<div class="level2">

<p>
The simplest possible way includes all changes since the local repository was syncronized with the repository at geda-project.org:
</p>
<pre class="code">$ git diff &gt; name_of_patchfile</pre>

<p>
A more complicated way with more control on what the patch contains:
</p>
<pre class="code">$ git add -i           # select files to be committed
$ git status           # check you&#039;re committing what you think you&#039;re committing
$ git commit           # create a commit
$ git format-patch -1  # create a patch file based on that commit</pre>

<p>
This will output a filename which contains the patch.  Be sure to look at the documentation for format-patch for more information.  This file can be e-mailed to developers who have write access and can be applied using git apply.
</p>

</div>
<!-- EDIT16 SECTION "format a patch to send to the developers?" [10859-11628] -->
<h2 class="sectionedit17"><a name="recover_from_a_really_messed_up_local_repository" id="recover_from_a_really_messed_up_local_repository">Recover from a really messed up local repository</a></h2>
<div class="level2">

<p>
First off, do not push any repository that you think is somehow messed up.  Ask one of the experienced git people first.
</p>

<p>
Second, the command that will really save your bacon is git-reflog.  Using it works something like this:
</p>
<pre class="code"> $ git reflog
 086908e... HEAD@{0}: cherry-pick: Last minute updates to the READMEs for all pro
 2a79a23... HEAD@{1}: checkout: moving to master
 2a79a23... HEAD@{2}: checkout: moving to master
 ...
 $ git reset --hard HEAD@{1}</pre>

<p>
The last command (git reset --hard ...) will rollback all your changes to the “checkout: moving to master”.  Remember: don&#039;t panic! Most things are fixable when using git.
</p>

</div>
<!-- EDIT17 SECTION "Recover from a really messed up local repository" [11629-] --></div>
</body>
</html>
